MacWorld: Complete Mac Interactive/Macworld Complete Mac Interactive CD)(1994).iso/The Best of BMUG/Entertainment/Strategy/Bolo/Bolo Utilities/BMAPEdit/BMAPEdit doc (text)

Text File | 1994-01-03 | 29KB | 264 lines

BMAPEdit
©1993-94 Carl R. Osterwald

A Macintosh application to create and edit maps for Bolo, the multi-player distributed tank battle game written by Stuart Cheshire.  BMAPEdit reads, edits, prints, and creates files (of type ‘BMAP’) for use with Bolo.†  It has been designed to provide you, the people who enjoy playing Bolo, with the tools needed to quickly and efficiently make creative maps.

BMAPEdit is shareware.  If you like and use BMAPEdit, please send $10.00 to:
    Carl R. Osterwald
    PO Box 15532
    Lakewood, Colorado 80215
This program may be freely distributed provided this documentation file is distributed also.  It may not be sold commercially.  This update is free to previously registered users.

Please send any comments, suggestions, or, most importantly, bug reports to:
    Internet:  [e-mail]
    or by physical mail to the address above.

SECTIONS IN THIS DOCUMENTATION:
    • 1.    Acknowledgments
    • 2.    Requirements
    • 3.    System 7 Compatibility
    • 4.    Bolo Maps
    • 5.    Map Windows
    • 6.    Drawing
    • 7.    Snap-To-Grid
    • 8.    Random Utilities
    • 9.    The ToolBox
    • 10.    Menus
    • 11.    Special Square Dialogs
    • 12.    Keyboard Shortcuts and Actions
    • 13.    Text Import/Export
    • 14.    Known Bugs
    • 15.    Warranty

1.    ACKNOWLEDGMENTS:
    • Stuart Cheshire:  for Bolo and for the code to read and write Bolo map files.
    • Tom Barrett & Stuart Cheshire:  for the Bolo preview graphics code.
    • Scott Knaster & Keith Rollin:  for “Macintosh Programming Secrets.”
    • Forrest Tanaka:  for the offscreen graphics code.
    • Peter Lewis:  for the random map generator & growth algorithms.
    • Phil Parilla:  for the self-avoiding random walk-maze algorithm.
    • Beta testing:
        Dan LaLiberte, Aaron Bratcher, Andrew Tennant, Phil Parilla, Eric Hiris, Russell Mast,
        Gavin Kistner, Bill Ingalls, John White, Brian Keyes, Chris Hanson, & Chip Benowitz.

†BMAPEdit does not read old-style ‘resource’ Bolo map files.  These files may be read and converted by opening them with the Bolo application and then saving to a new file.

2.    REQUIREMENTS:
    • Color Quickdraw (not available on Macs with 68000 CPUs such as Classics or SEs)
    • 750 kBytes of memory (prefers 1 MByte)
    • System 6.0.4 or greater
    • B&W printing requires a PostScript printer
    • Color/grayscale printing requires a PostScript Level 2 printer

BMAPEdit does not require a color monitor, but color will allow you to take full advantage of the display capabilities of BMAPEdit.

Each open map window requires 66 kBytes of memory.

3.    SYSTEM 7 COMPATIBILITY:
    • Required Apple events supported
    • Help balloons
    • 32-bit mode compatible

4.    BOLO MAPS:
Bolo maps use a grid of 256 by 256 squares.  Squares are numbered left-to-right and top-to-bottom starting at 0 and ending at 255.  Of these squares, the outer most 10 squares on all sides are filled with mines by Bolo (the outer minefield) and cannot have terrain placed in them.  Although refueling bases and pillboxes can be located in the outer minefield, the author of Bolo discourages this and a warning dialog box asking for confirmation is displayed when placement in the outer minefield is attempted.  Also, Bolo does not allow any terrain except deep water in an additional 10 square border inside of the mine field squares.  While this deep water border is intended for start squares (the invisible squares that define where tanks can enter the game), bases and pillboxes may also be located here if desired.  All regular terrain other than special squares is restricted to squares 20 through 235 horizontally, and 20 through 235 vertically.  The border of this area is called the terrain mapping limit rectangle in BMAPEdit.

5.    MAP WINDOWS:
The Bolo display shows the map squares in 16x16 pixel rectangles.  This corresponds to the Preview mode in the BMAPEdit Mag menu.  Three other modes, 12x12, 10x10 and 8x8, display the map data in reduced Bolo graphics.  Start squares are shown as a tank on a boat in deep water, pointed in the same direction as the start square’s direction.

The remaining display modes, 5x5, 3x3, and 1x1, use single colors to represent map terrain.  In B&W 3x3 and 1x1, land squares are black and water squares are white.  In 1x1 magnification, an entire Bolo map can be viewed in a window of only 256 by 256 pixels.  The colors used for the reduced display modes have been selected to allow distinction of terrain on monitors with only 16 colors available.  A key to the reduced colors is in the ToolBox below each of the terrain icons.  These colors can be customized by double clicking on the terrain icons, which brings up the standard Apple color picker.  Mines are shown as a yellow dot centered in terrain squares, or as a yellow ‘X’.  They are not displayed at 1x1, and the outer minefield is not displayed at magnifications below 5x5.  Start squares show up as a small red arrow or dot.

The border of the terrain mapping limit rectangle can optionally be displayed (see the Options menu).  The horizontal and vertical map coordinates are displayed in the floating ToolBox palette as the mouse is moved across the map window.

Map windows can be scrolled with the scroll bars, or with the ‘grabber’ hand that is activated by the pressing the space bar.

6.    DRAWING:
BMAPEdit uses a ‘foreground – background’ style where the foreground terrain is defined by the icon selected in the ToolBox, and the background terrain is selected through a popup menu at the bottom of the ToolBox, or a submenu in the Options menu.  All drawing applies the foreground terrain to make changes, while the background terrain is applied when a selected region is moved by dragging, rotation, or reflection, or when a selected region is cleared.

Drawing is done with five basic methods: pencil, line, filling, framing, and painting.  Of these, filling and framing are performed on regions defined with the selection tools in the ToolBox (the rectangle, rounded rectangle, oval, and polygon tools) by using the corresponding commands in the Utilities menu.  Pencil drawing, line drawing, and painting are done by clicking with the respective tools from the ToolBox.  Important—line drawing, filling, and framing apply the pattern currently selected in the Patterns menu, where a black pixel in the pattern changes the terrain in the map squares affected to the foreground, and white pixels cause no changes.  Many effects can be achieved with the patterns, including, for example, perfect ‘checkerboard’ mine fields.  Such a mine field would be laid down through the 50% gray pattern.  When BMAPEdit is first opened, the pattern defaults to solid black.

Pencil drawing changes individual map squares to the foreground terrain.  It operates in the traditional ‘paint’ program style.  Pencil drawing is also the primary way special squares—refueling bases, pillboxes, and start squares—are added to a map.  Filling, framing, painting, and line drawing do not apply to special squares.  Therefore, selecting the base, pillbox, or start square icons in the ToolBox automatically selects the pencil tool also.  Start squares are added to a map by clicking and dragging the pencil until the desired direction is indicated.  Special squares are also deleted with the pencil tool by holding the option key down, which then changes to a bulldozer cursor, and then clicking the base, pillbox, or start square.

Lines are drawn after a line segment has been selected by clicking and dragging with the line tool.  The line produced is affected by the current pattern, and its size is determined by the current line size setting in the Options menu.  The line tool can also be used to make square blocks quickly by selecting an appropriate line size and clicking on the map without dragging.  Lines drawn in road, water, or deep water terrain at line size equal to 1 produce a path that is traversable.  Holding down the option key while dragging a line with the line tool causes BMAPEdit to make a randomly-walked path with a line size of 1 (the line size setting in this case is ignored).

Filling is performed by selecting a region with a selection tool (see the ToolBox discussion below) and choosing the Fill Selection item in the Utilities menu.  Framing is similar, except that the line width used is determined by the current line size setting in the Options menu.

Painting is done by clicking with the paint bucket tool.  The Paint Bucket simply changes all the identical terrain squares adjacent to the click location to the foreground terrain.  It operates in the traditional ‘paint’ program style.  If the paint bucket is applied inside a selected region, painting is clipped to the selection boundary and will not go outside the boundary.

Mines and special squares represent special cases.  Mines can only be applied to existing swamp, crater, road, forest, rubble, or grass squares.  Attempting to place mines on any other types of terrain is ignored.  Start squares can only be placed in deep water.  If other terrain is subsequently applied to a start square, the start square is removed.  Also, bases and pillboxes ‘float’ above whatever terrain they have placed in, including deep water.  The terrain a base or pillbox sits on is what a map square becomes when that base or pillbox is moved during a game (currently, Bolo allows only pillboxes to be moved).  Note that it is possible to create completely unusable refueling bases by locating them in deep water, with all adjacent squares also deep water.  A tank can land at the base and refuel, but because boats cannot remain in deep water unoccupied, there is no way to leave the base without dying in deep water.

Please note that Bolo maps are currently limited to 16 of each type of special squares (bases, pillboxes, and start squares).  Attempting to add additional bases, for example, after the maximum number has been reached is simply ignored by BMAPEdit.

7.    SNAP–TO–GRID:
BMAPEdit has the ability to restrict drawing operations to an invisible grid.  The grid defaults to the minimum size of one square, but can be set to larger values with the Grid Size item in the Options menu (see the Menus section below).    A grid size of three, for example, will force the cursor to map squares evenly divisible by three, e.g., squares 3, 6, 9, 12, etc.  When dragging selections, the grid location used is always the upper left corner of the rectangle bounding the selected area.

Notice that it is possible to make a selection at a small grid size, increase the grid size, and then drag the selection into a new position relative to the new grid.  In this case, you will see two feedback rectangles as the selection is dragged.  The first is the original selection rectangle, and the second is the selection rectangle snapped to grid.  This second rectangle defines the area where the selected area will move to after dragging.

8.    RANDOM UTILITIES:
BMAPEdit has special utilities for adding random features to Bolo maps.  Several of these—random bases & PBs, random maps, random fills, random frames, make island, maze fill and city fills—are accessed through the Utilities menu and are discussed below.  Small random shapes or ‘blobs’ can be made with the pencil tool and the shift key pressed; random ‘walks’ or lines can be added with the line tool and option key held down.  See the keyboard shortcuts section for more information.

9.    THE TOOLBOX:
The ToolBox is a floating window that is divided into five sections.  These sections are, from top to bottom, the foreground terrain selection, current special square counts, the tool palette, the map coordinate display, and the background terrain popup menu.

The foreground terrain selection section is an array of terrain types, represented as icons, that can be applied to Bolo maps.  These icons are identical to the terrain squares as drawn by Bolo in a game.  Just below each icon is a color bar that shows which color is used to represent that terrain in the reduced color drawing modes (the color bars do not appear in B&W).  The bottom row of icons in the terrain palette are special squares, from left to right, refueling bases, pillboxes, and start squares.  Double clicking on the icons brings up the standard Apple color picker and allows the 1x1, 3x3, and 5x5 color display modes to be customized.  Clicking the zoom box in the upper right toggles the ToolBox between its full size and a minimum-sized bar.

The twelve tools in the tool palette are described next in left-to-right, top-to-bottom order.

The pointer tool performs three functions:  dragging selections, dragging special squares, and double-clicking special squares.  Moving selections by dragging them is straightforward, and following the move the terrain in the selection is replaced with the background terrain.  Once a selection has been dragged, it can be further dragged without affecting the map until the selection is ‘set’ (or the ‘paint has dried’) by selecting another tool, pressing the tab key, or by switching to another map window.  Special squares may be relocated without having to first select them with one of the selection tools.  Simply click and drag them to the new location.  Notice that this is different from dragging a selection because the terrain under the special square is not moved.  All dragging is pinned to the terrain limit rectangle (described above).  Finally, the settings of special squares may be adjusted by double-clicking them.  A double-click brings up a dialog window that will allow you to make whatever changes you desire.  The special square dialogs are described in more detail below.

The pencil and line tools are used for pencil and line drawing, as described above.  Dragging with the shift key down restricts lines to horizontal, vertical, and diagonal directions.

The magnifying glass is used to switch display modes.  Holding the option key down while clicking switches to a lower magnification, while a normal click produces the opposite effect.  Display modes may also be switched with the cmd + and cmd - keys.

Rectangle, rounded rectangle, and oval regions are selected with the next three tools, respectively.  Dragging with the shift key down causes square and circle regions to be selected, and if the option key was pressed when the mouse was clicked, the selections expand from the click location, causing the selection to be centered at this point.  Centered selections can be an even or odd number of squares wide and high, depending on the where the initial click is relative to the center of the square.  Option-clicks near the center produce odd width and height selections, otherwise the selection is even number of squares wide and high.

Polygons are selected with the polygon tool.  Each mouse click in succession adds another point to the polygon, up to a maximum of 128 points.  A double-click adds a final point and closes the polygon.  The previous polygon point can be deleted, before the final point is added, by holding the option key down and clicking.  Note that a polygon does not have to be open, i.e. a series of points can be closed by ‘doubling back’ to the first point.  The sequence of line segments produced can be framed, but not filled.

Selections can rotated or reflected perpendicular to a line with the rotator and reflector tools.  The original selection region is replaced with the background terrain unless the selection is not yet ‘set’ (or the ‘paint is still wet’).  After rotation or reflection, the selection can be dragged into final position without disturbing existing terrain until the selection is ‘set’.

The paint bucket has been described above in the drawing section.

Finally, you can add lettering to maps with the text tool.

10.    MENUS:

File menu—
The File menu is straightforward and all items have their usual meanings.  Bolo map files can be printed in B&W to a PostScript printer, or in color/grayscale to PostScript Level 2 printer, according to the settings in the LaserWriter print dialog window.  The output is intended as a navigational aid, and larger maps are printed with progressively smaller squares.  Color/grayscale printing will require significantly more time to print than B&W, and will cause a PostScript error if the printer selected in the Chooser is not a PostScript Level 2 printer.

Saving a map as a PICT produces a PICT file that shows the Bolo map drawn according to the export format selected in the Options menu.  Please note that these files can be quite large at larger magnifications and if color is desired.

The Save as/Open Text items allow importing and exporting Bolo maps using text files that can viewed without the Bolo application or a map editor such as BMAPEdit, using a standard set of ASCII characters.  See the section on text import/export for complete details of the character set.

Edit Menu—
The Edit menu follows the standard Macintosh format.  Map regions that have been copied or cut and then subsequently pasted can be dragged into final position using the pointer tool.  Map data that is in the clipboard is converted to a PICT image according to the export format selected in the Options menu, for export to other applications.  If the Auto Conversion item in the Options menu is checked, clipboard data is converted to PICT format automatically whenever BMAPEdit is switched to the background, or when Quit is selected in the File menu.  If automatic conversion is not enabled (the default setting), clipboard data can always be converted with the Convert Clipboard item.  Please note that large selections can consume large amounts of memory, especially when color conversion is requested.  It is therefore possible for the conversion to fail if not enough memory is available.

PICT images that are in the clipboard can be pasted into a map.  Terrain is determined by the colors in the image, and should correspond to the color bars in the ToolBox.  Red and yellow should be avoided as these are used for display of special squares and therefore are converted to the background terrain.

Select All selects a rectangular area that bounds the entire map while ignoring deep water.  If the map is empty, the entire editable area is selected.

The Clone item performs a two-step copy-paste operation that allows a copy of the selected area to be dragged away while leaving the original terrain untouched.

Mag Menu—
The Mag menu is used to switch magnification display modes.  Command-key equivalents are provided for convenience.  The Increase/Decrease items change magnification by one level and can be accessed through the +/- command keys on the keyboard or keypad.

Options menu—
Various settings can be altered with the Options menu.  Most of these have been discussed above, with the exception of Show PB Ranges which toggles display of the seven-square range of pillboxes.  The Random Fill % item allows the approximate percentage of a random fill to be selected.  Random fills are discussed in greater detail below.  The settings in the options menu are preserved in a preferences file.

Patterns menu—
The Patterns menu is used to select the Quickdraw pattern that is used for line drawing, filling, and framing selections.  It defaults to solid black, as discussed above.

Utilities menu—
The Utilities menu contains an assortment of operations that can be performed on Bolo maps.

The first three items, Remove Specials, Set to Default, and Random Bases & PBs, operate on the refueling bases, pillboxes, and start squares.  The Random Bases & PBs item is used to add a number of bases and PBs to a selected area, or throughout the entire map, at random locations.  Bases and pillboxes are never added over ‘liquid’ terrain, i.e. water, deep water, or boats.

The next three items, Clear Mines, Clear Boats, and Pave Craters, operate either on the entire map, or a selected area.  They are provided mainly for repair of maps that have been saved during a game.  Pave Craters allows you to replace craters with either road or grass.  Also, if you dislike mines at the beginning of a game they can be easily removed.

The Starter Map item will generate a quick rectangular map filled with grass and framed with water, and with start squares evenly distributed about the perimeter.  As an option, starter maps with the original Bolo map format (104x52) can also be generated.

The Random Map item randomly generates an entire Bolo map, including special squares if the appropriate checkboxes are selected in the Random Map dialog.  This utility is very similar to the RandomMapGenerator written by Peter Lewis (the algorithm was adapted from the source code for RandomMapGenerator).  Any existing terrain and all special squares are erased before the map is generated.  The map will be constrained to whatever region is currently selected, if desired, or a rectangular map centered in the Bolo grid can be selected as an alternative.  If the ‘Deep water inside map’ dialog item is not checked, the map region will be filled with shallow water before the map is generated.  Otherwise, islands generated will be framed with shallow water.  Pairs of bases can be linked with roads using the Connect Bases checkbox.

The Fill Selection and Frame Selection items have been discussed above in the Drawing section, and the Random Fill item is used randomly distribute the foreground terrain throughout a selection.  The amount of filling will be close to (but not precisely) the percentage as set in the Options menu.  This setting defaults to 20%.  The Random Frame item operates on rectangular or polygon selections and performs a random walk from point-to-point using the foreground terrain and a line size of one square.

The last three items, Make Island, Maze Fill, and City Fill, generate random fills in selections.

Make Island erases the selection with the background terrain, produces a randomly shaped island inside the selection, and then performs a fill, random fills, and then a frame as directed.  If a polygon is selected, the polygon is used and a random shape is not produced.  Small pinholes can be prevented with a checkbox selection in the Make Island dialog.

The Maze Fill item will produce a random maze in a rectangular selection with one entrance and one exit on opposite sides of the rectangle.  Terrain for the maze consists of the path terrain and the barrier terrain which are selected with popup menus in the maze dialog.  Thicknesses of the paths and barriers are then specified with scroll bars.  The maze generation algorithm requires an odd number of squares horizontally and vertically.  If an even number is selected, the maze size will be decreased by one.  On a 16MHz SE/30 Macintosh, production of a maze that fills the entire terrain mapping limit rectangle, 215x215 squares, requires about 2 minutes.

Random cities consisting of horizontal and vertical roads can be generated with the City Fill item inside of rectangular selections.  Note that parks, consisting mostly of trees, consume a total of four city blocks each.

See the keyboard shortcuts section for further information about producing random terrain.

Windows menu—
The Windows menu can be used to bring other map windows to the top, and to show the ToolBox if it has been closed.  The first item, Center Window, scrolls the top map window so that the center point, 128, 128, is in the center of the window.  This facility is provided because the author of Bolo recommends that maps be centered in the 256x256 point map grid.

11.    SPECIAL SQUARE DIALOG WINDOWS:
These dialogs, which are opened by double-clicking bases, pillboxes, or start squares with the pointer tool, allow all settings of these special squares to be selected, including initial ownership, base initial stocks, and pillbox firing intervals (a ‘mad’ pillbox fires with a shorter interval between shots).  Ownership is determined by the order in which players join a game, i.e., the second player to join would automatically own bases that have been set to an ownership of 2.  Base and pillbox numbering changes the logical order in which bases and PBs are listed, it does not have any visible effect on the map.  Base and pillbox numbering is used to make the base and PB displays in the Bolo game window correspond geographically with the bases and pillboxes on the map.  Bolo shows bases and pillboxes starting with number 1 in the top-left corner of the displays and continuing left-right top-to-bottom to number 16 (or to the total number of bases or PBs).  If the numbering is ignored, they are numbered in the order they were placed on the map.  Note that, in the case of pillboxes, this facility is of little use later in the game because PBs can be killed, moved, and ‘replanted’.

The start square dialog allows the start direction to be changed.

12.    KEYBOARD SHORTCUTS AND ACTIONS:
A number of keyboard shortcuts, in addition to the command-key equivalents of menu items, area are available to speed map editing.

Command key:
    • Produces the pointer cursor while pressed

Space bar:
    • Activates the ‘grabber’ hand for scrolling in map windows

Tab key:
      • Deselects any active selection

Shift key:
    • Dragging new selections with the shift key down produces squares, square ovals, and circles.
    • Dragging lines and adding polygon points with the shift key down restricts lines and new points to horizontal, vertical, and diagonal directions.
    • Changes pencil cursor to a ‘blob’ cursor which is used to generate random shapes in the foreground terrain.  The random shape only ‘grows’ on terrain identical to the click location in a way similar to the paint bucket.

Option key:
    • Changes magnifier cursor to demagnifier if demagnification is possible.
    • Changes pencil tool to bulldozer for removal of special squares.
    • Clicking and dragging the line tool with the option key pressed produces a random walk from the start to the end point.
    • If the option key was pressed when the mouse was clicked while dragging a new rectangle, rounded rectangle, or oval selection, the new selection expands from the click location, causing the selection to be centered at this point.
    • Clicking with the polygon tool causes the previous polygon point to be replaced.

ToolBox keyboard shortcuts:
    D:    Deep water
    W:    Water
    R:    Road
    G:    Grass
    F:    Forest
    M:    Mines
    C:    Crater
    B:    Base
    P:    Pillbox
    S:    Start square
    Arrow keys:  moves to next tool in direction of arrow

Start square dialog shortcuts:
    Tab:                selects next direction counter-clockwise (or anticlockwise)
    Option-Tab:    selects next direction clockwise
    Arrow keys:    selects corresponding cardinal direction (N, S, E, or W)

Additional shortcuts:
    Delete, clear:    clear selection (same as clear item in Edit menu)

13.    TEXT IMPORT/EXPORT:
Each terrain type is translated to/from an ASCII text character.  These are intended as a method of illustrating written discussions about strategy and tactics, especially when posted to the Usenet news groups.  Terrain that has been exported as text will have the proper appearance when displayed in a monospaced font such as Monaco or Courier.  If a proportionally spaced font is used, map squares in the same vertical column will not line up.

Several drawbacks with using these characters should be noted.  First, start squares loose their directionality.  Second, the terrain under mines is lost, i.e. there is no way to indicate whether a mine is on grass, swamp, road, rubble, crater, or trees.  Third, for a tank in a boat, there is no way to tell if it is in water or deep water.  Also, damage levels to pillboxes cannot be determined.  Finally, differentiation of ownership of bases and pillboxes for players 4 through 16 is not possible.  None of these will prevent the use of the character set as intended.  The terrain characters are:
deep water    ;
water    :
swamp    s
grass    blank (space)
road     +
forest    #
crater    c
rubble    r
shot building    %
building    O (not zero)
boat    b

neutral base    @
player 1 base    1
player 2 base    2
player 3 base    3
player 4..16 base    4
neutral pillbox    *
player 1 pillbox    7
player 2 pillbox    8
player 3 pillbox    9
player 4..16 PB    0 (not capital ‘O’)
visible mine    X
invisible mine    x
start square    S
tank    t
tank in boat    T

Please note that when importing text, all other visible characters are changed to grass.  Also, the terrain for ‘T’ is interpreted as either water or deep water depending on the surrounding map squares.  If the number of surrounding squares that are deep water is three or less, a ‘T’ is interpreted as water, otherwise it becomes deep water.  A carriage return (ASCII control-M) begins a new map row.  When exporting map terrain as text, all mines are invisible because visibility of mines is not defined in map files, but rather only while a game is in progress within Bolo itself.

14.    KNOWN BUGS:
Converting Bolo map clipboard data to PICT format  has occasionally resulted in crashes when the PICT is drawn, such when viewing the clipboard from the Finder.  This may be due to lack of memory.  The conversion process attempts to check and flag errors, but this may not work properly.  Please report any problems with the PICT conversion process to the author at the address above.

15    .WARRANTY:
There are no warranties.  The author makes no guarantees that BMAPEdit will perform as specified, or that its use will not completely ruin your computer (but it shouldn’t, it hasn’t ruined his).